home *** CD-ROM | disk | FTP | other *** search
/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / system / fortn411.zip / FORTUNE.DOC < prev    next >
Text File  |  1994-11-07  |  21KB  |  473 lines
  1. FORTUNE.DOC
  2. 11/07/94
  3.  
  4. The FORTUNE.EXE program adds some tuning features to the DOS FOR command (FOR
  5. tune, fortune, what the heck).  These features can in some way be applied to
  6. commands accepting regular DOS wildcards.  Features include:
  7.  
  8.  * Results of command are written to a batch file which you can review before
  9.    you run it.  Lets you subsequently edit it if desired and lets you see
  10.    exactly what commands will happen when you run it.
  11.  * Ability to embed redirection indicators in a command (see next example).
  12.  * Ability to separate the file name and file extension.  For example:
  13.         FORTUNE IN (*.TXT) DO SORT %[ %A %] %1*.SOR
  14.  * Ability to identify individual characters in the the file name and extension.
  15.    For example:
  16.         FORTUNE IN (*.TXT) DO RENAME %A (%1%2%3%4%5%6).*
  17.  * Ability to specify a character other than "%" for the delimiter so you can
  18.    avoid worrying about different syntax in batch command vs command line
  19.  * Ability to have batch file pause after each command so results can be
  20.    reviewed.
  21.  * Ability to specify incrementation in the file names.  For example:
  22.         FORTUNE IN (*.TXT) /+2 DO COPY %A %1*.%0001
  23.  * Ability to specify multiple statements on one command line.
  24.  * Ability to process children subdirectories (/S option) at same time.  For
  25.    example:
  26.         FORTUNE IN (\*.TXT) /S DO COPY %A D:\BACKUPS
  27.         FORTUNE *.BAT /S DEL %A
  28.  * Ability to exclude up to 10 file specifications from consideration.
  29.  * Ability to do those tough PKZIP commands that you always wanted to do.  Like
  30.    compress all *.FLI files in your subdirectory to a ZIP of the same name as
  31.    the original file:
  32.         FORTUNE *.FLI /DO PKZIP -M %R %e
  33.  * In addition, you can use the command to create a file which contains a
  34.    series of commands including a header and footer section which can be used
  35.    for some batch functions.
  36.  
  37.  
  38. The DOS FOR command:
  39.  
  40. Quite a few DOS users are unaware of the DOS FOR command.  It allows you to do a
  41. single command over a series of files and provides an easy way to use wildcards
  42. with commands that don't accept them.  For example, if you want to type a number
  43. of files to your screen, you can say something like:
  44.  
  45.         FOR %A IN (*.TXT) DO TYPE %A
  46.  
  47. DOS looks at your IN specification and figures out what file names are covered
  48. by that request.  The request can include path information if desired and can
  49. have multiple specification (e.g.  "...IN (*.TXT \BAT\*.DOC)...").
  50.  
  51. FOR then substitutes the file name itself in for whatever variable you specify
  52. in the first parameter after "FOR" ("%A" here).  This variable is a single
  53. character (A to Z) preceded by a single percent sign (%).  (If FOR is used in a
  54. batch command, you have to use two percent signs (%%) instead.)
  55.  
  56.  
  57. FOR then looks at the command following the keyword "DO" and executes that
  58. command.  If it finds the variable name in the command, it substitutes the name
  59. of the file for that variable.
  60.  
  61. So, in the above example, if you had three *.TXT files--ABLE.TXT, BAKER.TXT,
  62. and CHARLIE.TXT--and you ran the command, it would actually do three commands
  63. for you:
  64.  
  65.         TYPE ABLE.TXT
  66.         TYPE BAKER.TXT
  67.         TYPE CHARLIE.TXT
  68.  
  69. All in all, FOR is a *very* useful command.  There are also some DOS tricks that
  70. you can use to make the command even more useful but, frankly, I always forget
  71. the tricks.  (If someone would like to e-mail them to me, I'll throw them in
  72. here.) In any case, even past the tricks, the FORTUNE command provides even more
  73. features.
  74.  
  75.  
  76. FORTUNE wildcards and special characters:
  77.  
  78. The FORTUNE.EXE program extends the functionality of the DOS FOR command by
  79. providing ways of splitting up the parts of the file name and manipulating the
  80. parts.  For example, someone in my office had a mess of files that had to be
  81. renamed as an open parenthesis, followed by the first six characters of the file
  82. name, followed by a close parenthesis.  Not too terrible to handle with my text
  83. editor but it hadn't occurred to her.  Using FORTUNE, however, it's pretty easy:
  84.  
  85.         FORTUNE IN (*.TXT) DO RENAME %A (%1%2%3%4%5%6).*
  86.  
  87. And then you run the newly-created batch file (DOIT.BAT).
  88.  
  89. Similarly, someone wanted me to rename a mess of files so they had sequential
  90. names.  I had to write a program to handle it.  Definitely beyond his
  91. capabilities.  Again, using FORTUNE it's pretty easy:
  92.  
  93.         FORTUNE IN *.TXT DO RENAME %A %1*.%0001
  94.  
  95. And again you run the DOIT.BAT file.
  96.  
  97. Within the command (DO command), FORTUNE allows you to include a number of
  98. indicators.  The character which indicates that it's a special character is
  99. typically "%" but you can change this with the /VAR=char option in FORTUNE.
  100. (You can also set the default by using the CONFIGWS program.) All of the
  101. examples here use the default /VAR=% setting.
  102.  
  103. NOTE TO 4DOS USERS:  4DOS automatically translates %x characters even if used on
  104. the command line.  As such, 4DOS users *have* to use a different /VAR=x setting
  105. to use FORTUNE.  FORTUNE detects that you are running 4DOS and typically changes
  106. the default /VAR=x to /VAR=@.  This default can be changed by using the CONFIGWS
  107. program.
  108.  
  109.  
  110. In many cases, the indicators are case sensitive; there's a difference between
  111. %p and %P.  Typically, the lowercase variants are cumulative.  %P gives you just
  112. the path whereas %p throws in the drive information too.
  113.  
  114.      %a         translates into the entire file name (begins with drive,
  115.                 colon, \, path, \, file root, ., file extension).
  116.                 Use %R.%E if you want the filename without the drive/path info
  117.      %D         translates into the drive (not followed by :)
  118.      %d         translates into the drive (followed by :)
  119.      %P         translates into path (not preceded or followed by \)
  120.      %p         translates into path (begins with drive, colon, \, path, \)
  121.      %R         translates into file name root
  122.      %r         translates into file name root (begins with drive, colon, \,
  123.                 path, \)
  124.      %E         translates into file name extension
  125.      %e         translates into file name extension (begins with drive, colon,
  126.                 \, path, \, file name root, .)--same as %a
  127.      %1 to %8   characters 1 to 8 in the file name root
  128.      %X to %Z   characters 1 to 3 in file name extension (case insignificant;
  129.                 %X is the same as %x)
  130.  
  131. Standard DOS wildcards are supported within the file name.  So %1* will give you
  132. all characters in the file name root, %2* will give you all characters beginning
  133. with the second character.  "?" is also supported.  Wildcards outside of the
  134. special indicators work as expected ("...DO RENAME %A %1*.%X*" works
  135. identically to "...DO RENAME %A *.*").
  136.  
  137. All other characters in the command string are passed as given.
  138.  
  139.  
  140. Using the above characters, if you have two files C:\AUTOEXEC.BAT and
  141. D:\WAYNE\MYSTUFF.TXT, the various codes above translate as:
  142.  
  143.                 C:\AUTOEXEC.BAT         D:\WAYNE\MYSTUFF.TXT
  144.      %A         C:\AUTOEXEC.BAT         D:\WAYNE\MYSTUFF.TXT
  145.      %D         C                       D
  146.      %d         C:                      D:
  147.      %P         (null)                  WAYNE
  148.      %p         \                       D:\WAYNE\
  149.      %R         AUTOEXEC                MYSTUFF
  150.      %r         C:\AUTOEXEC             D:\WAYNE\MYSTUFF
  151.      %E         BAT                     TXT
  152.      %e         C:\AUTOEXEC.BAT         D:\WAYNE\MYSTUFF.TXT
  153.      %1         A                       M
  154.      %2         U                       Y
  155.      %3         T                       S
  156.      %4         O                       T
  157.      %5         E                       U
  158.      %6         X                       F
  159.      %7         E                       F
  160.      %8         C                       (null)
  161.      %X         B                       T
  162.      %Y         A                       X
  163.      %Z         T                       T
  164.  
  165.  
  166.  
  167. Special translations:
  168.  
  169.      %[         translates into <
  170.      %]         translates into >
  171.      %0nnnn     incrementer field (where "nnnn" is any number of digits;
  172.                 translates into a numeric field which has the same number of
  173.                 digits; the first number will be the value of "nnnn" and
  174.                 subsequent files will be incremented by the value specified in
  175.                 the /+n or /-n parameter (defaults to /+1)
  176.  
  177.  
  178.  
  179. Using a command file for special cases:
  180.  
  181. In addition, FORTUNE supports some options that might be used outside of a batch
  182. file.  (There are also several uses for this within a batch command but I won't
  183. go into them here.  Think about it on your own.) For example, let's say you have
  184. an FTP program and you want to log onto the site and upload all of the *.TXT
  185. files in your subdirectory.  Normally, you'd do this by typing something like
  186. this in response to the expected prompts:
  187.  
  188.         ftp
  189.         ftp.cu.nih.gov           (the name of the ftp site you're logging onto)
  190.         anonymous                (your userid--I know, anonymous logins aren't
  191.                                   trusted for uploads; use your own userid)
  192.         bgu@cu.nih.gov           (your password)
  193.         cd pub
  194.         cd incoming
  195.  
  196. Now, for each of the files you have, you'd have to enter a command like "send
  197. filename", typically followed by a blank line when prompted for the recipient
  198. file name.
  199.  
  200. Finally, after you're all done, you'd typically issue a "quit" command.
  201.  
  202. Thinking about it, you can use redirection in DOS to say "FTP < filename",
  203. as long as the lines in the text file "filename" contain all of the statements
  204. in sequence that you need to issue.
  205.  
  206. FORTUNE lets you specify a command file which contains a "header" section
  207. (commands to be sent beforehand), a "main" section (commands to be sent for each
  208. filename), and a "footer" section (commands to be send afterward).  Each section
  209. is optional and may consist of up to 20 commands.  In our example, your command
  210. file (we'll call it "FORTUNE.FTP" in this case) might look like this:
  211.  
  212.         /header
  213.         ftp
  214.         ftp.cu.nih.gov
  215.         anonymous
  216.         bgu@cu.nih.gov
  217.         cd pub
  218.         cd incoming
  219.         /main
  220.         send %A
  221.                                              (blank line)
  222.         /footer
  223.         quit
  224.  
  225. The commands within the "main" section are repeated for each file and can
  226. contain all of the standard FORTUNE features for the command section.
  227.  
  228. The sections can appear in any order.
  229.  
  230. To bring in the command file, specify "/DO @filename" instead of "/DO cmd".
  231. So, your command line might be:
  232.  
  233.         FORTUNE IN (*.TXT) DO @FORTUNE.FTP
  234.  
  235.  
  236. This will create a DOIT.BAT file which, in fact, does not contain batch command
  237. statements at all.  If this bothers you, specify a different output file name if
  238. you want.  Then, to process this file in your FTP command, use standard
  239. redirection:
  240.  
  241.         FTP < DOIT.BAT
  242.  
  243. Note that using the command file feature disables processing of the FORTUNE
  244. parameters which are specific to batch files.  These ignore parameters are:
  245. /ECHO, /-ECHO, /ABEND, /-ABEND, /PAUSE, and /-PAUSE.
  246.  
  247. In addition, you can specify a file that contains the filenames to process by
  248. using "/IN @filename".  This feature can be very handy when /-CHECK is specified
  249. and the file itself contains file names on a remote host.  For example, this is
  250. useful if you're trying to run something like FORTUNE on an ftp host over the
  251. Internet to issue a series of "get" commands on that host.
  252.  
  253. One disadvantage of the /-CHECK parameter is that it will not parse out the file
  254. name at all so only %A-like requests will do any good.
  255.  
  256.  
  257. The FORTUNE.INI file:
  258.  
  259. FORTUNE will read a FORTUNE.INI file if one is found.  (You can specify a
  260. different file name if desired.) The file is an ASCII text file that can be
  261. created maintained by hand.  The file can consist or one or more command line
  262. parameters (only those that begin with a "/"), one statement per line.
  263.  
  264. The file can also contain comments which are blank lines or any line beginning
  265. with:
  266.         ;    (semi-colon)
  267.         :    (colon)
  268.         '    (quote)
  269.  
  270. FORTUNE looks for the initialization file in your default subdirectory first.
  271. It then searches for it in the subdirectory where the executable was and then
  272. goes through your DOS path.
  273.  
  274. Passing in "/-I" or "/INULL" skips loading the FORTUNE.INI file.
  275.  
  276.  
  277.  
  278. CONFIGWS.EXE:
  279.  
  280. In addition to using the FORTUNE.INI file, you can permanently change some
  281. defaults within FORTUNE.EXE by using the CONFIGWS.EXE program.  CONFIGWS.EXE is
  282. not included in the FORTUNE distribution package but previous versions can
  283. typically be used with FORTUNE if desired.  (The same CONFIGWS.EXE program can
  284. be used to path a number of Wayne Software programs.) If CONFIGWS can't patch
  285. the executable, it will notify you of this before altering anything.
  286.  
  287. CONFIGWS.EXE allows you to set the following defaults:
  288.  
  289.         Variable char:  /VAR=char
  290.         Abort on error: /ABORT or /-ABORT
  291.         Echo commands:  /ECHO or /-ECHO
  292.         Pause between:  /PAUSE or /-PAUSE
  293.  
  294. When setting options, the program will process defaults in the following order:
  295.   (1) CONFIGWS.EXE-settable settings
  296.   (2) FORTUNE.INI settings
  297.   (3) command-line settings
  298.  
  299. The *last* settings encountered win.
  300.  
  301.  
  302. Syntax:
  303.  
  304.     FORTUNE { IN (set) | IN set | /IN (set) | /IN filespec | filespec }
  305.       [ /AS filename ] [ /OVERWRITE | /APPEND | /-OVERWRITE | /OVERASK ]
  306.       [ /VAR=char ] [ /DELIM=chars ] [ /+n | /-n ] [ /S ] [ /Xfilespec ] ...
  307.       [ /ECHO | /-ECHO ] [ /ABEND | /-ABEND ] [ /PAUSE | /-PAUSE ]
  308.       [ /CHECK | /-CHECK ] [ /Iinitfile | /-I ] [ /? ]
  309.       { DO cmd | /DO cmd | cmd }
  310.  
  311. where:
  312.  
  313. "IN (set)" lets you specify the file names to be processed.  Multiple file
  314. specifications should be separated by a space or a semicolon.  The "IN" can be
  315. preceded by a "/" if desired.  If only one file specification is provided, you
  316. can skip the parentheses.  You can specify "%PATH%" (depending on the value of
  317. the /DELIM=chars option) if you want.  A file specification is required for
  318. FORTUNE.
  319.  
  320. You can specify an input file that contains the file list to process.  This is
  321. done using "@filename" instead of "set" or "filespec".
  322.  
  323. It's possible to leave off the "IN" (or its derivatives) as well as the
  324. parentheses if your file specification(s) include a "/", "*", or "?" character.
  325. For example:
  326.  
  327.         FORTUNE *.BAS *.DOC DO TYPE %A
  328.  
  329. "/AS filename" tells the command the name of the batch file to create with the
  330. resulting commands.  By default, this file will be called DOIT.BAT and it will
  331. be created in your default subdirectory.
  332.  
  333.  
  334. "/OVERWRITE" says to write over any output file that's already there.
  335.  
  336. "/APPEND" says to add the new records at the end of any output file that's
  337. already there.  Note that FORTUNE uses several DOS labels every time it executes
  338. and concatenation is typically not recommended.
  339.  
  340. "/-OVERWRITE" says to abort if the output file exists already.
  341.  
  342. "/OVERASK" says to prompt if the output file exists already; this is the
  343. default.
  344.  
  345. "/VAR=char" indicates the character to use as the special character indicator.
  346. This typically defaults to "/VAR=%" under DOS and "/VAR=@" under 4DOS.  This
  347. default can be changed using the CONFIGWS program.  The hassle with this is that
  348. if you invoke FORTUNE from a batch file, you'll have to remember to use %%
  349. instead of %.  If you pick another character (like /VAR=^), that's not
  350. necessary.
  351.  
  352. "/DELIM=chars" allows you to indicate delimiters to use between statements
  353. within the DO command.  Defaults to "/DELIM=$$".  This allows you to process
  354. multiple statements in a single FORTUNE command.  For example:
  355.  
  356.         FORTUNE IN *.BAS DO COPY %A \TEMP $$ TYPE \TEMP\%R.%E
  357.  
  358. Note that the number of characters can be any length (including one character).
  359. Your only consideration is that the characters do not appear together in
  360. your command otherwise.  The characters are case insignificant ("/DELIM=newline"
  361. and "/DELIM=NEWLine" are the same thing).
  362.  
  363. "/+n" and "/-n" allow you to specify the increment/decrement value to be
  364. used where %0nnnn indicators are used in the command line.  Defaults to "/+1".
  365.  
  366. "/S" processes the children subdirectories as well.  So you could do something
  367. like any of the following:
  368.  
  369.         FORTUNE IN (\*.BAS) /S COPY %A LPT1:
  370.         FORTUNE IN (\OLD*.TXT) /S DO DELETE %A
  371.  
  372. The next example is a little bizarre.  Let's say you're using anti-virus
  373. protection program that maintains a read-only file in each subdirectory with all
  374. of the virus signatures for the files in that subdirectory.  You decide you no
  375. longer want to use that program again but you have a zillion of these files and
  376. they're all read-only.  The following example would search them all out, reset
  377. them to not be read-only, and then delete them.
  378.  
  379.         FORTUNE IN (\VIRCK.SIG) /S DO ATTRIB %A -R $$ DEL %a
  380.  
  381. "/Xfilespec" says to exclude certain filespecs from being considered.  You can
  382. specify up to 10 exclusion parameters but each must have their own /Xfilespec
  383. statement.  For example, you could process all *.BAS files except D*.BAS files
  384. by saying "FORTUNE IN (*.BAS) /XD*.BAS DO TYPE %A".
  385.  
  386.  
  387. "/ECHO" says to turn ECHO ON in the batch file.  This will show the command
  388. being executed before it executes.  This is typically the default but this can
  389. be changed using the CONFIGWS program.
  390.  
  391. "/-ECHO" says to turn ECHO OFF in the batch file.
  392.  
  393. "/ABEND" (abnormal end) says to use standard DOS errorlevel trapping to see if
  394. there was an error in running the command.  If any non-0 errorlevel condition is
  395. encountered (e.g.  an error has occurred), the batch file will branch out,
  396. skipping the rest of the statements in the batch file and aborting.  Note that
  397. not all commands return decent errorlevel codes.  COPY, for example, doesn't set
  398. an errorlevel to indicate that the file could not be found.  "/ABEND" is the
  399. typically the default but you can change this using the CONFIGWS program.
  400.  
  401. "/-ABEND" says to skip errorlevel testing.
  402.  
  403. "/PAUSE" says to add a PAUSE statement after each statement that's executed.
  404. If you don't like what you see, you can press Ctrl-Break and get out of the
  405. batch file.
  406.  
  407. "/-PAUSE" skips the PAUSE statements.  This is typically the default but you can
  408. change this using the CONFIGWS program.
  409.  
  410. "/Iinitfile" says to read an initialization file with the file name "initfile".
  411. The file specification *must* contain a period.  If no drive or path information
  412. is specified, the program will search for initfile beginning in your default
  413. subdirectory and then going throughout your DOS path.  The use of an
  414. initialization file is optional.  Initially defaults to "/IFORTUNE.INI".
  415.  
  416. "/-I" (or "/INULL") says to skip loading the initialization file.
  417.  
  418. "/?" or "/HELP" or "HELP" shows you the syntax for the command.
  419.  
  420. "DO cmd" (or "/DO cmd") specifies the command(s) to be executed.  A slash before
  421. "DO" is optional.  A DO (or /DO) command is required.  Multiple commands can be
  422. specified if they are separated using the characters specified in the
  423. /DELIM=chars parameter.  You can also use a command file by using /DO @filename;
  424. see the previous discussion on "Using a command file for special cases".
  425.  
  426. In most cases, the use of the "DO" (or "/DO") parameter is actually unnecessary.
  427. The routine typically treats all of the following as identical:
  428.  
  429.         FORTUNE IN (*.BAS *.DOC) /DO TYPE %A
  430.         FORTUNE IN (*.BAS *.DOC) TYPE %A
  431.         FORTUNE *.BAS *.DOC TYPE %A
  432.  
  433. However, using the "DO" (or "/DO") parameter adds an extra left of error
  434. checking and its use it encouraged.
  435.  
  436.  
  437.  
  438. Return codes:
  439.  
  440. FORTUNE returns the following ERRORLEVEL codes:
  441.         0 = no problems, files found and batch file created
  442.         1 = no problems, no files met specifications
  443.       255 = syntax problems, file not found, or /? requested
  444.  
  445.  
  446. Author:
  447.  
  448. This program was written by Bruce Guthrie of Wayne Software.  It is free for use
  449. and redistribution provided relevant documentation is kept with the program, no
  450. changes are made to the program or documentation, and it is not bundled with
  451. commercial programs or charged for separately.  People who need to bundle it in
  452. for-sale packages must pay a $50 registration fee to "Wayne Software" at the
  453. following address.
  454.  
  455. Additional information about this and other Wayne Software programs can be found
  456. in the file BRUCEymm.DOC which should be included in the original ZIP file.
  457. ("ymm" is replaced by the last digit of the year and the two digit month of the
  458. release.  BRUCE312.DOC came out in December 1993.  This same naming convention
  459. is used in naming the ZIP file that this program was included in.) Comments and
  460. suggestions can also be sent to:
  461.  
  462.                 Bruce Guthrie
  463.                 Wayne Software
  464.                 113 Sheffield St.
  465.                 Silver Spring, MD 20910
  466.  
  467.                 fax: (301) 588-8986
  468.  
  469. See BRUCEymm.DOC file for additional contact information.
  470.  
  471. Foreign users:  Please provide an Internet e-mail address in all correspondence.
  472.  
  473.